[skip changelog] Specify that includes field items should be in library
#1305
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…rary
The library.properties `includes` field specifies a custom list of files to be added to the sketch by the IDE as
`#include` directives. Library authors sometimes add filenames from library dependencies to this field. However, that
doesn't make any sense because all Arduino development software versions with support for the `includes` field have also
had support for resolution of the dependencies of libraries, meaning that there is no need for these `#include`
directives to be placed in the sketch.
For this reason, Arduino Lint rule LP052 ("library.properties includes field item(s) not found in library.") was
configured as an error when the tool is in the default "specification" compliance mode. Since the required rules in this
mode are intended to match the official Arduino Library Specification, it is important that mention be made in the
`includes` field that it should contain files of the library itself.
Since this requirement is fairly common sense, and the format of the library.properties fields documentation somewhat
constraining, I attempted to document it with minimal verbosity.
per1234
added
type: bug
topic: documentation
umbynos
approved these changes
Jun 3, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Please check if the PR fulfills these requirements
before creating one)
our contributing guidelines
UPGRADING.mdhas been updated with a migration guide (for breaking changes)Docs update
The library.properties
includesfield specifies a custom list of files to be added to the sketch by the IDE as#includedirectives. Library authors sometimes add filenames from library dependencies to this field. However, that doesn't make any sense because all Arduino development software versions with support for theincludesfield also have support for resolution of the dependencies of libraries, meaning that there is no need for these library dependency#includedirectives to be placed in the sketch.For this reason, Arduino Lint rule
LP052("library.properties includes field item(s) not found in library.") was configured to be an error when the tool's compliance setting is at the default "specification" level.The required rules in "specification" mode are intended to match the official Arduino Library Specification, however, the is currently no mention in the Arduino Library Specification of any restrictions on the contents of the library.properties
includesfield.The Arduino Library Specification's documentation of the
includesfield mentions that it should contain files of the library itself.Since this requirement is fairly common sense, and the format of the library.properties fields documentation somewhat
constraining, I attempted to document it with minimal verbosity.
titled accordingly?
Not a breaking change.